/*
 * 代号：凤凰
 * http://www.jphenix.org
 * 2022年8月21日
 * V4.0
 */
package com.jphenix.standard.servlet.api;

import java.io.InputStream;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Enumeration;
import java.util.EventListener;
import java.util.Set;

import com.jphenix.servlet.exception.ServletException;
import com.jphenix.standard.docs.ClassInfo;

/**
 * Servlet上下文
 * 
 * 2022-09-04 隔离了ServletApi，兼容新老Tomcat
 * 
 * @author MBG
 * 2022年8月21日
 */
@ClassInfo({"2022-09-04 21:58","Servlet上下文"})
public interface IServletContext {
	
	/**
	 * 返回临时路径
	 * 即：ServletContext.TEMPDIR
	 * @return 临时路径
	 * 2022年8月21日
	 * @author MBG
	 */
	String getTempDir();
	
	/**
	 * 返回排序后的包文件路径
	 * 即：ServletContext.ORDERED_LIBS
	 * @return 排序后的包文件路径
	 * 2022年8月21日
	 * @author MBG
	 */
	String getOrderedLibs();
	
	/**
	 * 返回上下文路径
	 * @return 上下文路径
	 * 2022年8月21日
	 * @author MBG
	 */
	String getContextPath();

	/**
	 * 通过名uri路径获取Servlet上下文
	 * @param uripath uri路径
	 * @return 对应的Servlet上下文
	 * 2022年8月21日
	 * @author MBG
	 */
	IServletContext getContext(String uripath);

	/**
	 * 返回主版本号
	 * @return 主版本号
	 * 2022年8月21日
	 * @author MBG
	 */
	int getMajorVersion();

	/**
	 * 返回小版本号
	 * @return 小版本号
	 * 2022年8月21日
	 * @author MBG
	 */
	int getMinorVersion();

	/**
	 * 返回实际的主版本号
	 * @return 主版本号
	 * 2022年8月21日
	 * @author MBG
	 */
	int getEffectiveMajorVersion();

	/**
	 * 返回实际的小版本号
	 * @return 实际的小版本号
	 * 2022年8月21日
	 * @author MBG
	 */
	int getEffectiveMinorVersion();

	/**
	 * 返回指定资源的Mime类型
	 * @param file 资源相对路径
	 * @return Mime类型
	 * 2022年8月21日
	 * @author MBG
	 */
	String getMimeType(String file);

	/**
	 * 获取指定资源的路径信息
	 * @param path 指定资源的相对路径
	 * @return 路径信息
	 * 2022年8月21日
	 * @author MBG
	 */
	Set<String> getResourcePaths(String path);

	/**
	 * 通过资源相对路径返回资源的URL信息
	 * @param path 资源相对路径
	 * @return            资源的URL信息
	 * @throws MalformedURLException 异常
	 * 2022年8月21日
	 * @author MBG
	 */
	URL getResource(String path) throws MalformedURLException;

	/**
	 * 返回指定资源的读取流对象
	 * @param path 资源相对路径
	 * @return 指定资源的读取流对象
	 * 2022年8月21日
	 * @author MBG
	 */
	InputStream getResourceAsStream(String path);

	/**
	 * 输出日志
	 * @param msg 日志内容
	 * 2022年8月21日
	 * @author MBG
	 */
	void log(String msg);

	/**
	 * 输出日志
	 * @param message    日志内容
	 * @param throwable 异常类实例
	 * 2022年8月21日
	 * @author MBG
	 */
	void log(String message, Throwable throwable);

	/**
	 * 返回资源的绝对路径
	 * @param path 资源相对路径
	 * @return            资源的绝对路径
	 * 2022年8月21日
	 * @author MBG
	 */
	String getRealPath(String path);

	/**
	 * 获取服务器信息
	 * @return 服务器信息
	 * 2022年8月21日
	 * @author MBG
	 */
	String getServerInfo();

	/**
	 * 获取指定的初始化参数值
	 * @param key     参数名
	 * @return        参数值
	 * 2022年8月21日
	 * @author MBG
	 */
	String getInitParameter(String key);

	/**
	 * 返回所有初始化参数名
	 * @return 初始化参数名
	 * 2022年8月21日
	 * @author MBG
	 */
	Enumeration<String> getInitParameterNames();

	/**
	 * 设置初始化参数
	 * @param key   参数名
	 * @param value 参数值
	 * @return      是否设置成功
	 * 2022年8月21日
	 * @author MBG
	 */
	boolean setInitParameter(String key, String value);

	/**
	 * 获取属性值
	 * @param key 属性主键
	 * @return    属性值
	 * 2022年8月21日
	 * @author MBG
	 */
	Object getAttribute(String key);

	/**
	 * 返回所有属性主键
	 * @return 所有属性主键
	 * 2022年8月21日
	 * @author MBG
	 */
	Enumeration<String> getAttributeNames();

	/**
	 * 设置属性值
	 * @param key    属性名
	 * @param value  属性值
	 * 2022年8月21日
	 * @author MBG
	 */
	void setAttribute(String key, Object value);

	/**
	 * 移除指定属性值
	 * @param key 属性主键
	 * 2022年8月21日
	 * @author MBG
	 */
	void removeAttribute(String key);

	/**
	 * 返回Servlet上下文名
	 * @return 上下文名
	 * 2022年8月21日
	 * @author MBG
	 */
	String getServletContextName();

	/**
	 * 返回Cookie配置信息类
	 * @return Cookie配置信息类
	 * 2022年8月21日
	 * @author MBG
	 */
	ISessionCookieConfig getSessionCookieConfig();

	/**
	 * 添加监听器
	 * @param className 监听器类名
	 * 2022年8月21日
	 * @author MBG
	 */
	void addListener(String className);

	/**
	 * 添加监听器
	 * @param <T>
	 * @param t 监听器实例
	 * 2022年8月21日
	 * @author MBG
	 */
	<T extends EventListener> void addListener(T t);

	/**
	 * 添加监听器
	 * @param listenerClass 监听器类
	 * 2022年8月21日
	 * @author MBG
	 */
	void addListener(Class<? extends EventListener> listenerClass);

	/**
	 * 创建监听器
	 * @param listenerClass 监听器类
	 * @return              监听器实例
	 * @throws ServletException 异常
	 * 2022年8月21日
	 * @author MBG
	 */
	<T extends EventListener> T createListener(Class<T> listenerClass) throws ServletException;

	/**
	 * 获取类加载器
	 * @return 类加载器
	 * 2022年8月21日
	 * @author MBG
	 */
	ClassLoader getClassLoader();

	/**
	 * 获取虚拟服务器名
	 * @return 虚拟服务器名
	 * 2022年8月21日
	 * @author MBG
	 */
	String getVirtualServerName();

	/**
	 * 返回会话超时时间
	 * @return 会话超时时间（分）
	 * 2022年8月21日
	 * @author MBG
	 */
	int getSessionTimeout();

	/**
	 * 设置会话超时时间
	 * @param sessionTimeout 会话超时时间（分）
	 * 2022年8月21日
	 * @author MBG
	 */
	void setSessionTimeout(int sessionTimeout);

	/**
	 * 返回请求数据编码格式
	 * @return 请求数据编码格式
	 * 2022年8月21日
	 * @author MBG
	 */
	String getRequestCharacterEncoding();

	/**
	 * 设置请求参数编码格式
	 * @param encoding 请求参数编码格式
	 * 2022年8月21日
	 * @author MBG
	 */
	void setRequestCharacterEncoding(String encoding);

	/**
	 * 获取返回数据编码格式
	 * @return 返回数据编码格式
	 * 2022年8月21日
	 * @author MBG
	 */
	String getResponseCharacterEncoding();

	/**
	 * 设置返回数据编码格式
	 * @param encoding 返回数据编码格式
	 * 2022年8月21日
	 * @author MBG
	 */
	void setResponseCharacterEncoding(String encoding);
}
